// 《围棋》作者版权所有。版权所有。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

package strings

import (
	"unicode/utf8"
	"unsafe"
)

// 生成器用于使用写方法高效地构建字符串。
// 它最大限度地减少了内存复制。零值已准备好使用。
// 请勿复制非零生成器。
type Builder struct {
	addr *Builder // 的接收器，通过值检测拷贝
	buf  []byte
}

// noescape在转义分析中隐藏指针。noescape是
// 标识函数，但escape分析认为
// 输出不依赖于输入。noescape是内联的，目前
// 编译到零指令。
// 小心使用！
// 这是从运行时复制的；见问题23382和7921。
// go:nosplit 
// go:nocheckptr 
func noescape(p unsafe.Pointer) unsafe.Pointer {
	x := uintptr(p)
	return unsafe.Pointer(x ^ 0)
}

func (b *Builder) copyCheck() {
	if b.addr == nil {
		// 这项黑客技术解决了go的逃逸分析失败
		// 导致b逃逸并被堆分配的问题。
		// 见第23382期。
		// TODO:一旦问题7921得到解决，应将其恢复为
		// 仅为“b.addr=b”。
		b.addr = (*Builder)(noescape(unsafe.Pointer(b)))
	} else if b.addr != b {
		panic("strings: illegal use of non-zero Builder copied by value")
	}
}

// String返回累计字符串。
func (b *Builder) String() string {
	return *(*string)(unsafe.Pointer(&b.buf))
}

// Len返回累计字节数；b、 Len（）==Len（b.String（））。
func (b *Builder) Len() int { return len(b.buf) }

// Cap返回构建器底层字节片的容量。它是为正在生成的字符串分配的总空间，包括已写入的所有字节。
func (b *Builder) Cap() int { return cap(b.buf) }

// 重置将生成器重置为空。
func (b *Builder) Reset() {
	b.addr = nil
	b.buf = nil
}

// grow将缓冲区复制到新的更大的缓冲区，以便在len（b.buf）之外至少有n个
// 字节的容量。
func (b *Builder) grow(n int) {
	buf := make([]byte, len(b.buf), 2*cap(b.buf)+n)
	copy(buf, b.buf)
	b.buf = buf
}

// 如果需要，增加b的容量，以保证为
// 再增加n个字节的空间。在Grow（n）之后，至少可以将n个字节写入b 
// 而无需另一次分配。如果n为负，则增加恐慌。
func (b *Builder) Grow(n int) {
	b.copyCheck()
	if n < 0 {
		panic("strings.Builder.Grow: negative count")
	}
	if cap(b.buf)-len(b.buf) < n {
		b.grow(n)
	}
}

// Write将p的内容附加到b的缓冲区。
// Write始终返回len（p），nil。
func (b *Builder) Write(p []byte) (int, error) {
	b.copyCheck()
	b.buf = append(b.buf, p...)
	return len(p), nil
}

// WriteByte将字节c追加到b的缓冲区。
// 返回的错误始终为零。
func (b *Builder) WriteByte(c byte) error {
	b.copyCheck()
	b.buf = append(b.buf, c)
	return nil
}

// WriteRune将Unicode代码点r的UTF-8编码附加到b的缓冲区中。
// 返回r的长度和一个零错误。
func (b *Builder) WriteRune(r rune) (int, error) {
	b.copyCheck()
	// 比较as uint32以正确处理负面符文。
	if uint32(r) < utf8.RuneSelf {
		b.buf = append(b.buf, byte(r))
		return 1, nil
	}
	l := len(b.buf)
	if cap(b.buf)-l < utf8.UTFMax {
		b.grow(utf8.UTFMax)
	}
	n := utf8.EncodeRune(b.buf[l:l+utf8.UTFMax], r)
	b.buf = b.buf[:l+n]
	return n, nil
}

// WriteString将s的内容附加到b的缓冲区。
// 返回s的长度和一个零错误。
func (b *Builder) WriteString(s string) (int, error) {
	b.copyCheck()
	b.buf = append(b.buf, s...)
	return len(s), nil
}
